=============
Contributions
=============

.. highlight:: none

Contributions are welcome, bug fixes and `SASL mechanisms`_ in particular.
If you want to contribute another feature, consider `filing a feature
request <https://github.com/odkr/sievemgr/issues/new>`_ first, so that we
can discuss things beforehand.


STANDARDS
=========

Please target Python version 3.9 and follow :pep:`8`, :pep:`20`, :pep:`257`
as well as the spirit of Robert Pike's `Notes on Programing in C
<https://doc.cat-v.org/bell_labs/pikestyle>`_. Code should pass `linting
<LINTERS_>`_ and the `test suite <TESTING_>`_. But you are welcome to `ask
for help <https://github.com/odkr/sievemgr/discussions>`_ if you are stuck.


LINTERS
=======

SieveManager ships with configurations for:

* Bandit_
* Dlint_
* Flake8_
* MyPy_
* Ruff_
* PyLint_
* vermin_
* vulture_

It would be kind of you if you made sure that your code passes every linter
before your submit it. However, feel free to skip as many of them as you like
if you do not want to install that many applications. Bandit_ and MyPy_ are
the important ones.

Install the above linters::

    pip3 -r linters.txt

Run MyPy_, Bandit_, and vermin_ only::

    make quicklint

Run all linters::

    make lint

Set the `sources` macro to override which files are linted, for example::

    make lint sources=sievemgr.py 


TESTING
=======

Code should pass the test suite before being submitted.
Please add tests for your code, too.

Run the test suite::

    make check

Skip slow tests::

    make quickcheck

Set the `checks` macro to override which tests are run, for example::

    make checks=tests.test_acap check


AUTOMATION
==========

Run

.. code:: bash
    
    git config core.hooksPath .githooks

to automatically run :command:`make quicklint` and :command:`make quickcheck` 
before each commit and :command:`make lint` and :command:`make check`
before each push.

.. note::

   :file:`.githooks` only ships with the Git respository.
   It is not included in the tarball.


VERSION CONTROL
===============

SieveManager uses Git_ and follows the `Git Flow`_ branching model. The
source code is hosted at `Codeberg <repo-primary_>`_ (primary) and
`NotABug <repo-secondary_>`_ (secondary).


PULL REQUESTS
=============

Fork SieveManager on `Codeberg <repo-primary_>`_
or `NotABug <repo-secondary_>`_.

Download the ``devel`` branch of your fork::

    git clone --branch devel "git@${host:?}:${username:?}/sievemgr.git"

Set up SieveManger as upstream source::

    git remote add upstream git@codeberg.org:odkr/sievemgr.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

   vi sievemgr.py

Commit, rebase, and push::

    git add sievemgr.py
    git commit -S -m 'feat: added support for foo'
    git pull --rebase upstream devel
    git push origin feat-foo

.. important::
   Please sign your commits.

Finally, submit your pull request. 


PATCHES
=======

You can also send a patch to the :file:`@zoho.com`
address listed in my `PGP key`_.

Download the ``devel`` branch::

    git clone --branch devel "git@codeberg.org:odkr/sievemgr.git"

Set up SieveManger as upstream source::

    git remote add upstream git@codeberg.org:odkr/sievemgr.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

    vi sievemgr.py

Commit and rebase::

    git add sievemgr.py
    git commit -S -m 'feat: added support for foo'
    git pull --rebase upstream devel

Create a patch::

    git diff HEAD HEAD~1 >foo.patch

Please sign your patch::

    gpg -ab foo.patch
